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Preface 


This document describes the Transferable Output ASCII Data (TOAD) Gateway, release 1 .0. It is intended 
to serve as a “cookbook" reference for all users. New users are directed to read the introductory section, 
then study the sample sessions presented in appendix A. Readers not familiar with the TOAD format are 
referred to appendix B of this document, or to NASA Contractor Report 178361 

Because of the ongoing development of this package, the current software release may offer substantially 
more translator options than what is documented here. However, all data formats discussed within this 
document will continue to be available on all future releases of the Gateway. 

This software was developed by Computer Sciences Corporation, Applied Technology Division, under 
contract to the National Aeronautics and Space Administration's Langley Research Center, during the 
Autumn of 1989 and early Winter of 1990. CSC supports this package only at Langley Research Center. 
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Introduction 


General Description and Purpose 

The Transferable Output ASCII Data (TOAD) Gateway is a software tool for converting tabular data from 
one format into another via the TOAD format. For example, the Gateway can be used to convert a wind 
tunnel Standard Interface File (SIF) into input for a PC spreadsheet program. This initial release of the 
Gateway allows free data interchange among the following file formats: TOAD; Standard Interface File 
(SIF); Program to Optimize Simulated Trajectories (POST) input; Comma Separated Value (CSV) and Tab 
Separated Value (TSV), used extensively as input to PC and Macintosh spreadsheet and database 
packages; and a general free-form file format. As required, additional formats can be accommodated 
quickly and easily. 

Features 

The major features offered by the Gateway are: 

Dialogue Driven - Because the Gateway asks all the necessary questions, and accepts a 
variety of plain English answers, even new or occasional users can effectively transform their data 
files. 

Automatic Formatting - When it opens an incoming data file, the Gateway automatically 
determines its format. This feature is particularly handy when receiving unfamiliar data files from 
unknown or foreign sources. 

Consolidation - An attempt has been made to include most data formats used at Langley into 
this software package. This allows Langley's researchers to use this "data gateway” for their data 
transformations. 

Error Messages - All error messages are written in plain English and every effort has been 
made to describe the problem as clearly as possible. A complete list of all error messages, 
including a further explanation and suggested remedies, is presented in appendix C. 

Portability - Perhaps the Gateway's most enduring feature is its ability to execute on a variety of 
operating systems. Developed under UNIX, it also executes under VMS and NOS. 


Limits 

The Gateway reads and writes entire data files, not file fragments. Consequently, there is an upper limit on 
the total number of raw data cells it can accommodate. The capacity of the Gateway is 1000 columns of 
data and 10,000 raw data cells. However, these capacities may change as the Gateway is installed on 
various hosts. Both limits are set once in a central part of the Gateway and are easily modified. If and when 
a data file exceeds either limit, a clear error message is written. 
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Associated Products 


A companion package, the TOAD Editor , allows the user to selectively review, extract, and manipulate the 
contents of TOAD files. Both the TOAD Gateway and the TOAD Editor are available and supported at 
NASA Langley Research Center. 
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Files 


I n t e r a c t T v e Use 


The user is responsible for ensuring that all incoming data files are available to the Gateway. This normally 
requires that "read" permission be granted to the user, the default on most systems. The exception is 
NOS. where the file can only be made available ("local”) by using the command 

get, filename 

where filename is the name of the permanent file to be made local. In addition, the files created can only 
be retained (“saved") by using the command 

save, filename 

or 

rep lace , filename 

where filename is the name of the local file to be made permanent. (Femember the NOS command save 
makes a local file permanent only when a permanent file l>y that name doesn’t already exist; the replace 
command always makes the local file permanent, whether a permanen’ file by that name already exists or 
not.) 

Execution 

How the Gateway is executed depends upon the host computer system. Most installations require only 
that 

toadgw 

be entered to begin execution. Again the exception is NOS, where the commands 

get,toadgw/un=ntfllb 

toadgw 

are required. The following welcome banner then appeals: 


TOAD Gateway 
Release 1.0 December 1990 


The release number and date will change as new versions of the Gateway are installed. 
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Incoming Data File 

The first question is: 

What is the name of the incoming data file ? 

A file name must be provided - the Gateway cannot assume a file name. The file name must be valid for the 
host operating system. Also, the file must exist, and it must not be in use (or “locked ) by another user or 
another process. Finally, the file cannot be empty. If any of these conditions are not met, the Gateway 
writes an error message and repeats the question. (For more information regarding a specific error 
message, please refer to Appendix C - Warnings and Error Messages.) 

The Gateway may be stopped here by entering “quit", “qui", or “q". 

After the file is opened, the Gateway attempts to match its contents to a recognized data file format. This 
process is invisible to the user. Once a match is made, the Gateway writes the message 


"filename" is in TOAD format, 
in the case of a TOAD file. Other formats generate a similar message. 


Outgoing Data File 

The next question is: 

What name should be given to the new file being created ? 

A file name must be provided - the Gateway cannot assume a file name. The file name must be valid for the 
host operating system. If the file does not already exist, it is created in the active directory. Otherwise the 
message 

This file already exists. Do you want it overwritten ? 

appears. Answering “yes” tells the Gateway to go ahead and overwrite the file. Entering “no” instructs it 
to ignore that file name and ask for another. 

The Gateway may be stopped here by entering “quit", "qui", or “q”. 

Outgoing Data File Format 

The next question is: 

Which data format should be used for the new file ? 

The Gateway attempts to match the format name provided with an internal list of formats supported. For 
example, either Toad" or “toa" is accepted as a request for a TOAD file. The other formats have 
comparable abbreviations and aliases. For a com plete list of the available formats, and their 
abbreviations/aliases, answer this question with “help" or “?". 

The Gateway may be stopped here by entering “quit”, “qui”, or "q". 
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Recycle Dialogue 

The final question is: 


Do you wish to convert another file ? 

If another file is to be translated, enter “yes" or “y" This starts the dialogue cycle again, beginning with the 
incoming data file question. Even if the cycle is restarted by mistake, the Gateway stops when any 
questions are answered with a “quit", “qui”, or “q". 

If no other file is to be translated, enter “no", “n”, “quit", “qui". or “q”. 
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In Case of Problems... 


:| 


General 

No software is above design and development errors. If you uncover an error, or notice some strange 
behavior, please follow the steps described below. One minute of your time may save hours or even days 
of effort. 

Langley Users - All Systems 

If possible, assemble the following information: 

1. Your host computer's manufacturer, model, operating system, and location. 

2. The incoming data file name. 

3. The desired outgoing data format. 

Then call Bradford Bingel (“Bing”) at Computer Sciences Corporation, (804) 865-1725. Every attempt will 
be made to correct the problem, when possible, yvttiTma ts w minutes - 


Non-Langley Users - All Systems 

Computer Sciences Corporation does not support the TOAD Gateway outside of NASA Langley. All 
questions and problems concerning this software should be directed to Dr. John E. Lamar, mail stop 361, 
( 804 ) 864 - 2851 . 


All comments are appreciated and welc&i ngd_Ul 
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Appendix A 
Sample Sessions 


Samp/e Session #1 

This first example illustrates how the Gateway's "auto-format" feature 
may be used to determine the format of an individual data file. 


% toadgw 


TOAD Gateway 
Release 1*0 December 1990 


What is the name of the incoming data file ? 

> testl2 

”te3tl2” is in TOAD format. 

What name should be given to the new file being created ? 

> q 

% 
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Samp/e S ess/on #2 


This second example illustrates a complete Gateway dialogue, 
including an assortment of error conditions and their corresponding 
messages. 


% toadgw 


TOAD Gateway 
Release 1,0 December 1990 


What is the name of the incoming data file ? 

> testl2 

”testl2" is in TOAD format. 

What name should be given to the new file being created ? 

> testpl2 

Which data format should be used for the new file ? 

> post 

Do you wish to convert another file ? 

> y 


What is the name of the incoming data file ? 

> 14 

”14” is an improper file name. 

What is the name of the incoming data file ? 

> test!4 

” test 14” is in SuperCalc CSV format. 

What name should be given to the new file being created ? 

> scl4 

This file already exists. Do you want it overwritten ? 

> y 
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” 3014 " will be rewritten. 

Which data format should be used for the new file 

> help 

The following data formats are available: 


TOAD 

toad 

toa 

SIF 

sif 


POST 

post 

pos 

CSV 

CSV 

cs (comma separated values) 

TSV 

tsv 

ts (tab separated values) 

FREE 

free- 

-field free-form free fre 


Which data format should be used for the new file 

> toad 


Do you wish to convert another file ? 

> x 


> n 


Please answer with a YES or a NO. 


Normal session. 


% 
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, • Appendix B 
The TOAD Format (summarized) 


The Transferable Output ASCII Data (TOAD) format was developed by Computer Sciences Corporation for 
NASA Langley Research Center as a uniform way to store and retrieve tabulated data. A full discussion of 
the TOAD format is presented in NASA Contractor Report 178361 . However, most readers will find the 
following abbreviated description adequate for their purposes. 

TOAD files are sequential-access, formatted, and use fixed-length records of 80 characters. This file type 
makes them simple to edit, write to or read from magnetic media, or send across communications 
networks. Unfortunately, these same characteristics make them large compared to their unformatted, 
variable record-length counterparts. Therefore, we recommend that TOAD files be used only when 
relatively small amounts of data are to be retained (less than 5000 pieces of data), or when any amount of 
data must be transferred from one computer to another (usually different) computer via magnetic media or 
a communications network. 

Blocks of information within a TOAD file are called "warts." Each wart has its own purpose, and may use 
one or more records. For example, consider the abbreviated TOAD file below: 

BEGIN 

SKIP Predicted aerodynamic properties of a modified F-4D fighter 
COUNT 9 

LABELMACH ALPHA 2Y/B CL-V CD-V 

CM-V CL-Z CD-Z CM-Z 


DATA 

. 85000000E+00 

. 10000000E+01 

. 70800000E+00 

. 97261000E+00 

. 151 66000E+00 


-.24139000E+00 

. 88951000E+00 

. 11 640000E+00 

- . 24754000E+00 


DATA 

. 85000000E+00 

. 10000000E+01 

. 79200000E+00 

. 894 15000E+00 

. 11423000E+00 


- . 27911000E+00 

. 78920000E+00 

* 69700000E-01 

- . 27105000E+00 


DATA 

. 85000000E+00 

. 10000000E+01 

. 87500000E+00 

. 78330000E+00 

. 72870000E-01 


- . 29796000E+00 

. 65651000E+00 

. 1 9080000E-01 

- . 26920000E+00 


END 







Notice that the file begins with a BEGIN wart and ends with an END wart. The SKIP wart is used to insert 
comments inside the file. The COUNT wart indicates that there are 9 variables in this TOAD file. The 
LABEL wart assigns a 15-character name with each of these variables. Each DATA wart contains 
information gathered at some common event. For example, the second DATA wart indicates that at Mach 
.85, 10 degrees angle of attack, and at 79.2% semispan the full vortex flow coefficients of lift, drag and 
moment (q, C d and C m ) are .89415, .11423 and -.27911, respectively, while the zero leading-edge 

suction coefficients of lift, drag and moment are .7892, .0697 and -.27105, respectively. 


The FORTRAN 77 edit descriptors for each type of wart are: 


Wart Type Wri t e Fo r ma t 


Read Formal 


SKIP 

COUNT 

LABEL 

DATA 


'SKIP ' , A75 
'COUNT' , 115 
'LABEL' , (5A15) 
'DATA • , (5E15. 8) 


T6, A75 
T6, 115 
(T6, 5A15) 
(T6, 5E15 .8) 
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The following rules must always be observed when creating and using TOAD files: 

1 . Exactly one BEGIN wart must appear in the TOAD file, and it must be the very first record. 

2. Exactly one END wart must appear in the TOAD file, and it must be the very last record. 

3 . A COUNT wart must appear before any LABEL or DATA warts. 

4. No wart may come between two records within another multi-record wart. 

5. SKIP warts may appear anywhere in the TOAD file, subject to condition 4. 

6. Multiple DATA warts are expected. All DATA warts must contain the same amount of data and 
use the same number of records. 

7. There is no limit on the number of warts or records in a TOAD file. 
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Appendix C 

Warnings and Error Messages 

The TOAD Gateway generates few error messages. Each was designed to be self-explanatory, but 
occasionally they may be misinterpreted. The purpose of this appendix is to clarify the situation creating 
the error and, where appropriate, suggest techniques which may help to avoid similar problems in the 

future. 

All error messages are presented in alphabetical order. 


” filename " appears to be empty. 

The file exists, yet contains no information. On most operating systems this is possible when 
some previous I/O operation created a new file without transferring any data. 


"filename" does not exist. 

The requested file does not exist, or the file exists but "read" permission is denied. Note that file 
names are case sensitive on UNIX installations (i.e. , file “DATAI" is unique from file datal ). 


"filename" doesn't look like a TOAD file. 

The incoming data file has all of the outward appearances of a valid TOAD file, yet something it 
contains has caused a fatal read error. Files using other formats may create similar messages. 


"filename" Is already In use. 

The requested file exists, but another user (or another process) has it "locked," making it 
inaccessible to the Gateway. 

"filename" Is an Improper file name. 

The file name provided is not valid on the host operating system. The most common problems are 
having a number as the first character, or using some special character (!<§>#$%) anywhere in the 
name. 


" filename " is a reserved file name. 

The file name provided is reserved for use only by the host operating system. For example, file 
stdout is reserved under UNIX, and SYS$INPUT is reserved under VMS. 
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" filename " will be rewritten. 

The outgoing file specified already exists. Its original contents will be lost as the Gateway writes 
the new information in its place. 


Internal Fatal Error - Ghost File. 

Please contact the TOAD Gateway support team. 

Internal fatal errors appear when logic errors occur within the software. Please accept the 
developer's apologies for any consequential inconvenience, and follow the steps listed in the 
section “In Case of Problems . . to report this message. 


Internal Fatal Error - Improper I/O Unit Passed. 

Please contact the TOAD Gateway support team. 

Internal fatal errors appear when logic errors occur within the software. Please accept the 
developer's apologies for any consequential inconvenience, and follow the steps listed in the 
section “In Case of Problems . . .” to report this message. 


Internal Fatal Error - Unknown Error Code. 

Please contact the TOAD Gateway support team. 

Internal fatal errors appear when logic errors occur within the software. Please accept the 
developer's apologies for any consequential inconvenience, and follow the steps listed in the 
section in Case of Problems . . .” to report this message. 


Please answer with a YES or a NO. 

The preceding question asked for a simple yes/no response. The Gateway accepts any of the 
following: y es, y, n o, or n . In addition, the Gateway stops when any of the following responses 
are entered: quit, qui, q. Any other response appears as an unclear answer. 


Sorry, but couldn't understand your answer. 

Please try again. 

For some unknown reason, the Gateway did not receive the user's response. This usually occurs 
after an unsuccessful attempt to alter a response by using a series of control characters. 


This file doesn't appear to be sequential. 

All data file formats currently accepted by the Gateway are sequential-access, as opposed to 
direct-access or word-addressable. If the incoming file is direct-access or word-addressable, this 
message appears. 
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Unable to open this file. Please try another. 

For any of a number of reasons, the requested file cannot be accessed. This situation should be 
somewhat rare, as most of the more common causes (e.g., the file doesn't exist, or it's locked by 
another user) are successfully diagnosed to create pinpoint explanations. The underlying cause 
is usually system-dependent, putting the Gateway in the unenviable position of writing this 
general error message. The only recommended remedy is to stop the Gateway, reestablish all file 
connections, and reexecute. 


Unable to open this TOAD file • Insufficient capacity. 

Only number words of central memory are available. 

The Gateway cannot dynamically allocate central memory. Consequently, there is a limit placed on 
the amount of central memory it may use to store the incoming raw data. If the file exceeds this 
limit, this message appears. When possible, a quick solution is to break up the file into two or 
more smaller files. However, if this message begins to appear regularly, please follow the steps 
listed in the section “In Case of Problems . . and ask for the Gateway's total capacity to be 
increased. 


Unable to open this TOAD file • Insufficient capacity. 

Only number columns are allowed. 

The Gateway cannot dynamically allocate central memory. Consequently, there is a limit placed on 
the amount of central memory it may use, and on the total number of "columns" it may handle. If 
the incoming data set uses more columns than the Gateway can handle, this message appears. 
When possible, a quick solution is to break up the file into two or more smaller files. However, if 
this message begins to appear regularly, please follow the steps listed in the section “In Case of 
Problems . . and and ask for the Gateway's column capacity to be increased. 


Unclear or unavailable format. 

The incoming data file is not in a recognized format. Those formats which are recognized by the 
Gateway, along with their abbreviations/aliases, are then listed below the error message. If you 
would like to see a new data format added to the Gateway's vocabulary, or believe that additional 
aliases are needed for an existing format, please follow the steps listed in the section “In Case of 
Problems . . ." and ask for the enhancement. 
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